.TH "frovedis::matrix_factorization_model<T>" "" "" "" ""
.SH NAME
.PP
\f[C]matrix_factorization_model<T>\f[] \- A data structure used in
modeling the outputs of the frovedis matrix factorization using ALS
algorithm
.SH SYNOPSIS
.PP
\f[C]#include\ <frovedis/ml/recommendation/matrix_factorization_model.hpp>\f[]
.SS Constructors
.PP
matrix_factorization_model ()
.PD 0
.P
.PD
matrix_factorization_model (size_t num_row, size_t num_col,
.PD 0
.P
.PD
\  \  \  \  \  size_t factor, size_t seed=0)
.PD 0
.P
.PD
matrix_factorization_model (const
\f[C]matrix_factorization_model<T>\f[]& model)
.PD 0
.P
.PD
matrix_factorization_model (\f[C]matrix_factorization_model<T>\f[]&&
model)
.SS Overloaded Operators
.PP
\f[C]matrix_factorization_model<T>\f[]& operator= (const
\f[C]matrix_factorization_model<T>\f[]& model)
.PD 0
.P
.PD
\f[C]matrix_factorization_model<T>\f[]& operator=
(\f[C]matrix_factorization_model<T>\f[]&& model)
.SS Public Member Functions
.PP
T predict (size_t uid, size_t pid)
.PD 0
.P
.PD
\f[C]std::vector<T>\f[] predict_all (const
\f[C]std::vector<std::pair<size_t,size_t>>\f[] IDs)
.PD 0
.P
.PD
\f[C]rowmajor_matrix_local<T>\f[] predict_all()
.PP
\f[C]std::vector<std::pair<size_t,T>>\f[] recommend_products(size_t uid,
int num)
.PD 0
.P
.PD
\f[C]std::vector<std::pair<size_t,T>>\f[] recommend_users(size_t pid,
int num)
.PP
void save (const std::string& path)
.PD 0
.P
.PD
void savebinary (const std::string& path)
.PD 0
.P
.PD
void load (const std::string& path)
.PD 0
.P
.PD
void loadbinary (const std::string& path)
.PP
size_t get_rank ()
.PD 0
.P
.PD
void debug_print ()
.PD 0
.P
.PD
\f[C]node_local<matrix_factorization_model<T>>\f[] broadcast()
.SH DESCRIPTION
.PP
\f[C]matrix_factorization_model<T>\f[] models the output of the frovedis
matrix factorization using ALS (alternating least square) algorithm, the
trainer interface of which aims to optimize an initial model and outputs
the same after optimization.
This model has the below structure:
.IP
.nf
\f[C]
template\ <class\ T>\ 
struct\ matrix_factorization_model\ {\ \ \ \ 
\ \ std::vector<T>\ X;\ \ //\ user\-feature\ vector\ of\ the\ size\ numRows*factor
\ \ std::vector<T>\ Y;\ \ //\ product\-feature\ vector\ of\ the\ size\ numCols*factor
\ \ size_t\ numRows;
\ \ size_t\ numCols;
\ \ size_t\ factor;
\ \ SERIALIZE\ (X,\ Y,\ numRows,\ numCols,\ factor)
};
\f[]
.fi
.PP
This is a template based data structure, where "T" is supposed to be
"float" (single\-precision) or "double" (double\-precision).
Note this is a serialized data structure.
The detailed description can be found in subsequent sections.
.SS Constructor Documentation
.SS matrix_factorization_model ()
.PP
Default constructor.
It creates an empty matrix factorization model with numRows = numCols =
factor = 0.
.SS matrix_factorization_model (size_t num_row, size_t num_col,
.PP
\  \  \  \  \ size_t factor, size_t seed)
.PD 0
.P
.PD
Parameterized constructor.
It accepts number of rows(M), number of columns(N), latent factor(F) and
seed value in order to create a model with "X" matrix of the dimension
MxF and "Y" matrix of the dimension NxF initialized with random numbers
according to the given seed.
.SS matrix_factorization_model (const
\f[C]matrix_factorization_model<T>\f[]& model)
.PP
Copy constructor.
It accepts an lvalue object of the same type and deep\-copies the same
in the newly constructed object.
.SS matrix_factorization_model (\f[C]matrix_factorization_model<T>\f[]&&
model)
.PP
Move constructor.
It accepts an rvalue object of the same type and instead of copying, it
moves the contents in the newly constructed object.
.SS Overloaded Operator Documentation
.SS \f[C]matrix_factorization_model<T>\f[]& operator= (const
\f[C]matrix_factorization_model<T>\f[]& model)
.PP
It deep\-copies the contents of the input lvalue model into the
left\-hand side model of the assignment operator "=".
.SS \f[C]matrix_factorization_model<T>\f[]& operator=
(\f[C]matrix_factorization_model<T>\f[]&& model)
.PP
Instead of copying, it moves the contents of the input rvalue model into
the left\-hand side model of the assignment operator "=".
.SS Pubic Member Function Documentation
.SS T predict (size_t uid, size_t pid)
.PP
This method can be used on a trained model in order to predict the
rating confidence value for the given product id, by the given user id.
.PP
"uid" should be in between 0 to numRows\-1.
.PD 0
.P
.PD
And "pid" should be in between 0 to numCols\-1.
Otherwise exception will be thrown.
.SS \f[C]std::vector<T>\f[] predict_all (const
\f[C]std::vector<std::pair<size_t,size_t>>\f[] IDs)
.PP
This method can be used to predict the rating confidence values for a
given list of pair of some user ids and product ids.
.PP
In the list of pairs, "uid" should be in between 0 to numRows\-1.
.PD 0
.P
.PD
And "pid" should be in between 0 to numCols\-1.
Otherwise exception will be thrown.
.PP
On successful prediction, it returns the predicted scores in the form of
\f[C]std::vector<T>\f[].
.SS \f[C]rowmajor_matrix_local<T>\f[] predict_all ()
.PP
This method can be used in order to predict the rating confidence values
for all the users and for all the products.
Thus internally it performs a product of X and Y component of the model
(X * Yt) and returns the resultant scores in the form of a
\f[C]rowmajor_matrix_local<T>\f[] with MxN dimension, where M is the
number of rows in X component and N is the number of rows in Y
component.
This method is useful in case of debugging the model.
.SS \f[C]std::vector<std::pair<size_t,T>>\f[] recommend_products(size_t
uid, int num)
.PP
This method can be used to recommend given "num" number of products for
the user with given user id in sorted order (highest scored products to
lowest scored products).
.PP
"uid" should be in between 0 to numRows\-1.
.PD 0
.P
.PD
If num > numCols, then "numCols" number of products would be
recommended.
On success, it returns a vector of pairs containing recommended product
ids and their corresponding rating confidence scores by the given user.
.SS \f[C]std::vector<std::pair<size_t,T>>\f[] recommend_users(size_t
pid, int num)
.PP
This method can be used to recommend given "num" number of users for the
product with given product id in sorted order (user with highest scores
to user with lowest scores).
.PP
"pid" should be in between 0 to numCols\-1.
.PD 0
.P
.PD
If num > numRows, then "numRows" number of users would be recommended.
On success, it returns a vector of pairs containing recommended user ids
and their corresponding rating confidence scores for the given product.
.SS size_t get_rank ()
.PP
It returns the latent factor of the target model.
.SS void save (const std::string& path)
.PP
It saves the target model in the specified path in simple text format.
It will throw an exception, if any error occurs during the save
operation.
.SS void savebinary (const std::string& path)
.PP
It saves the target model in the specified path in (little\-endian)
binary data format.
It will throw an exception, if any error occurs during the save
operation.
.SS void load (const std::string& path)
.PP
It loads the target matrix factorization model from the data in
specified text file.
It will throw an exception, if any error occurs during the load
operation.
.SS void loadbinary (const std::string& path)
.PP
It loads the target matrix factorization model from the data in
specified (little\-endian) binary file.
It will throw an exception, if any error occurs during the load
operation.
.SS void debug_print()
.PP
It prints the contents of the X and Y components of the model on the
user terminal.
It is mainly useful for debugging purpose.
.SS \f[C]node_local<matrix_factorization_model<T>>\f[] broadcast ()
.PP
It broadcasts the target model to all the participating MPI processes
(worker nodes) in the system.
This is an efficient implementation (as it does not involve
serialization overhead of the X and Y components of the model) than
simple "frovedis:broadcast(model)" call.
.SS Public Data Member Documentation
.SS X
.PP
An T type vector used to model the user\-feature matrix of the model.
.SS Y
.PP
An T type vector used to model the product\-feature matrix of the model.
.SS numRows
.PP
A size_t attribute containing the number of rows in X component of the
model.
.SS numCols
.PP
A size_t attribute containing the number of rows in Y component of the
model.
.SS factor
.PP
A size_t attribute containing the latent factor of the model.
